feat(cli): surface outdated CLI and skills to agents; add hyperframes update --check by Vitozhu04 · Pull Request #7094 · heygen-com/hyperframes

Vitozhu04 · 2026-11-03T14:15:15Z

Follow-up to #7013. The CLI and agents now notice an outdated CLI or outdated skills, and hyperframes update --check reports both in one call.

What

Check interval 24h → 2h for the CLI update check and the skills check. The skills nudge is still printed at most once a day per project (its own 24h window), and the 1h failure backoff in launchBackgroundChecks is unchanged.
Stale cache. A cached npm latest that is older than the running CLI is now due for a recheck on the next run. Before this, it waited out the full interval; fix(cli): the latest version in _meta is never older than the running CLI #7049 already hid that value from _meta. _meta gains checkedAt. Note: fix(cli): the latest version in _meta is never older than the running CLI #7049 chose to keep the daily cadence in this case, and this PR deliberately changes that. The 1h attempt backoff still caps how often the check retries.
Agents see outdated skills in _meta. Every --json output now carries _meta.skillsOutdated: <n>, read from the cached background skills check, so the main process makes no network call. The cache is stamped with the CLI version whose release tag it was compared against (skillsCheckedVersion). A count taken under another version is left out and rechecked. A count more than 24h old is also left out (see the Genesis fix below). Unattended runs still print nothing on stderr for outdated-only skills (fix(cli): add help [cmd], suggest the closest command or flag, and quiet the nags #6621). HYPERFRAMES_SKIP_SKILLS=1 omits the field.
New hyperframes update [--check] [--yes] [--json]. It runs one forced check of the CLI (npm, past the cache) and of the skills (manifest at the CLI's release tag).
- --check only reports.
- Without --check, it upgrades the CLI through the same plan and argv as upgrade --yes: upgradePlan is now shared, and the installer's output goes to stderr so a --json stdout stays one object. It then runs updateSkills at the release tag of the CLI that is now installed. For npm, pnpm and bun that is the exact version they pinned. For Homebrew it is the version the linked binary reports after brew upgrade: the outcome is unchanged when the formula has not moved, and unverified when the version can't be read. In both cases the skills stay at this CLI's tag.
- An unattended run without --yes exits 2, like upgrade.
- Under a plugin (HYPERFRAMES_PLUGIN_VERSION, set by plugin-cli.mjs), update reports but refuses to install (exit 1, plugin_managed), and skills are never touched.
- update is excluded from the background-check/notice block, like upgrade and skills.
doctor names the running binary and its path: npm/pnpm/bun global, Homebrew, project node_modules, npx/bunx, workspace link, or plugin. Its update hint is the command for that install, for example npx hyperframes@latest for npx and project-local runs (it was hyperframes upgrade for everyone). upgrade's fallback for unmanaged installs also prints npx hyperframes@latest. bunx's bunx-*/node_modules/… layout is now recognized as ephemeral (it used to read as unknown).
_meta.updateNotice: the agent relays, the person updates. When the CLI or the skills are behind, a --json result carries one sentence addressed to the person, e.g. "For the user: HyperFrames CLI 0.9.8 is available (this run is 0.9.6), and 3 installed HyperFrames skills are out of date. To update both, run: npx hyperframes update".
- The command is npx hyperframes update (npx hyperframes@latest update from an npx run, whose cache can hold the old CLI). A Homebrew install names brew upgrade hyperframes, or its own hyperframes update when the skills are behind too, since an npx copy would put the skills at npm's tag rather than brew's.
- The skills half is left out when no skill is behind or under HYPERFRAMES_SKIP_SKILLS=1. The whole notice is left out under CI, dev, HYPERFRAMES_NO_UPDATE_CHECK=1 and an agent plugin (HYPERFRAMES_PLUGIN_VERSION), and from update's own output.
- It appears at most once a day per project, through the same daily claim as the stderr skills nudge under its own key (update-notice.json; claimDailyNotice moved to utils/dailyNotice.ts). updateAvailable, latestVersion, checkedAt and the skills counts stay on every result.
_meta.skillsMissing: core skills not installed, next to skillsOutdated, under the same rules (this CLI version's tag, dropped after 24h, absent under HYPERFRAMES_SKIP_SKILLS=1).
One line in skills/hyperframes-cli/SKILL.md, naming no command: "A --json result may carry _meta.updateNotice: a newer HyperFrames release is out. Pass it to the person once per conversation, in your own words, at a natural pause; updating is theirs to decide." Why: no skill text tells the agent to install, update or remove skills, even gated on consent. Skill graders (e.g. DeltaVerdict D5) fail any such line as self-modification of the agent's other skills, and they read skill source, not CLI output. The command lives in the CLI's notice, for the person to run. The Upkeep row is unchanged. The hyperframes-cli size budget in scripts/check-core-skills.mjs goes from 7168 to 7424 B for this line, and skills-manifest.json is regenerated.
update wording. The confirmation hint (an agent run without --yes) now reads "Ask the person first; pass --yes only when they asked to update. --check only reports." update --check's skills command is npx hyperframes update, the same command _meta.updateNotice names, so this PR recommends one command for the job. skills update still works.
plugin-cli.mjs is unchanged: it still pins the CLI and disables the nudges.

Genesis review fixes (at fadf861).

brew upgrade installs the formula's version (which trails npm) and exits 0 on a no-op. update --yes now reads the installed version back and puts the skills at that tag. It no longer claims "upgraded to ".
The nit: I chose to drop the count rather than add a checkedAt. _meta.skillsOutdated is dropped once the cached count is over 24h old, so it can't freeze when HYPERFRAMES_NO_UPDATE_CHECK (or CI/dev) stops the background checks.

4 new tests fail at fadf861: brew stays behind npm, brew moves to an in-between version, brew's version can't be read, and a 25h-old count. A 23h-old count is still reported; that guard passes on both.

How tested

Unit tests (vitest, targeted files only, 18 files, 354 pass on the branch). 52 new or changed tests fail on main (they were run against base sources with the branch tests):

Item	Fail on main	Where
4 · 2h interval	3	`updateCheck.test`, `skillsUpdateCheck.test`, `backgroundChecks.test` (plus a once-a-day-per-project guard that passes on both)
5 · stale cache + `checkedAt`	2	`updateCheck.test` (the #7049 test now expects due=true)
6 · `_meta.skillsOutdated`	5	`updateCheck.test` (count with no network call, zero), `skillsUpdateCheck.test` (version stamp, other-version cache, pre-stamp cache)
7 · `update`	21	`update.test.ts`, per channel through the real installer detection, `upgrade` plan and `updateSkills`; only spawn, config, manifest and registry are stubbed
8 · doctor + channels	21	`doctor.install.test.ts` (10), `installerDetection.test.ts` `runningInstall` (11)

Every install channel is covered in update.test.ts (--check and the install path), and in installerDetection.test.ts / doctor.install.test.ts: npm -g, pnpm, bun, Homebrew, npx, bunx, project-local, workspace and plugin. cli.agentMode.test.ts adds update to the "refuses to prompt, names --yes, exits 2" case (passes locally with bun). Lint (oxlint/oxfmt), fallow, the comment ratchet and citations, test reachability and the docs command check all pass.

updateNotice / skillsMissing (at 609b89e). 14 new tests in updateCheck.test.ts. They cover the full CLI+skills sentence; missing core skills in the skills half; a skills-only notice; the skills half dropped when none is behind and under HYPERFRAMES_SKIP_SKILLS; brew (brew upgrade hyperframes, and hyperframes update with skills behind); npx (@latest); absence under the update-check opt-out, CI, the plugin env, nothing behind, and { updateNotice: false }; once a day per project with the numeric fields still present on the second result and the notice back the next day; and a daily claim kept apart from the skills nudge's. skillsMissing has 5: reported, dropped when over a day old, taken under another version, not a count, or under HYPERFRAMES_SKIP_SKILLS. Targeted runs: updateCheck, skillsUpdateCheck, update, backgroundChecks, updateCheck.stalepin, autoUpdate.invocation, installerDetection, doctor.install (8 files, 172 pass), plus the update cases of cli.agentMode.test.ts (9 pass). check-core-skills, lint-skills, check-skill-mirror, gen-skills-manifest --check, test reachability and oxlint/oxfmt on the changed files pass.

Sandbox journeys, main vs branch. Each run used an isolated HOME and npm prefix/cache, HYPERFRAMES_NO_TELEMETRY=1, and env -i. Built bundles were laid out at each channel's real path, and two journeys used the real npm/npx installs.

Journey	main (`b2acef5`)	branch
J1: cache checked 10 min ago says latest 0.9.6, running 0.9.8	no recheck; `_meta` never gets latest	background recheck on run 1; run 2 `_meta` = latest 0.9.8 + `checkedAt`
J2: agent `info --json`, skills at v0.9.6 under CLI 0.9.8	cache knows 2 outdated, `_meta` doesn't say; stderr empty	`_meta.skillsOutdated: 2`; stderr empty (a missing core skill still prints)
J3: `update --check --json`	unknown command (2 calls needed)	CLI + skills in one object (0.9.6→0.9.8 / `ref v0.9.6`; or 2 outdated at `v0.9.8`)
J3 real: `update --yes --json` on a real `npm i -g hyperframes@0.9.6`	n/a	npm installed 0.9.8, then skills cloned at `@ v0.9.8` (hyperframes-cli, media-use); stdout one JSON object
J4: Homebrew 0.9.6, attended, latest 0.9.8	notice `brew upgrade hyperframes`, no spawn	same; `update --check` names brew; explicit `update --yes` calls brew
J4: plugin env	no background checks	same; `update --check` reports `plugin`, skills skipped; `update --yes` exit 1 `plugin_managed`
J5: `doctor` npm-global / npx / project	hint `hyperframes upgrade` for all, no path	`CLI binary` line with channel + path; hint `npm install -g hyperframes@0.9.8` / `npx hyperframes@latest` (also via a real `npx hyperframes@0.9.6`)

Please don't add to the merge queue; merge after owner OK.

— wanbi

🤖 Generated with Claude Code

mintlify · 2026-11-03T14:15:19Z

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
hyperframes	🟢 Ready	View Preview	Nov 4, 2026, 8:36 AM

💡 Tip: Enable Automations to automatically generate PRs for you.

github-actions · 2026-11-03T14:23:11Z

Edit accuracy: accurate 267 (base branch 267), smooth 115 of those

The gate passes.
Smoothness is reported in the artifact, not gated. A case fails only if it fails 2 of 3 runs.

Quarantined, measured but not gated (8)

seqplainkeys-none-center-r0-nested-z100 (fixed by studio: undo/redo on a keyframed plain element sometimes leaves the box 230-400px off (edit-accuracy seqplainkeys-none-*) #6989): pass, passes
seqplainkeys-none-center-r0-root-z100 (fixed by studio: undo/redo on a keyframed plain element sometimes leaves the box 230-400px off (edit-accuracy seqplainkeys-none-*) #6989): pass, passes
seqplainkeys-none-center-r30-root-z100 (fixed by studio: undo/redo on a keyframed plain element sometimes leaves the box 230-400px off (edit-accuracy seqplainkeys-none-*) #6989): not run
seqplainkeys-none-pct-r0-root-z100 (fixed by studio: undo/redo on a keyframed plain element sometimes leaves the box 230-400px off (edit-accuracy seqplainkeys-none-*) #6989): pass, passes
seqplainkeys-none-pct-r30-root-z100 (fixed by studio: undo/redo on a keyframed plain element sometimes leaves the box 230-400px off (edit-accuracy seqplainkeys-none-*) #6989): not run
seqplainkeys-none-px-r0-nested-z100 (fixed by studio: undo/redo on a keyframed plain element sometimes leaves the box 230-400px off (edit-accuracy seqplainkeys-none-*) #6989): pass, passes
seqplainkeys-none-px-r30-nested-z100 (fixed by studio: undo/redo on a keyframed plain element sometimes leaves the box 230-400px off (edit-accuracy seqplainkeys-none-*) #6989): not run
seqplainkeys-none-px-r30-root-z100 (fixed by studio: undo/redo on a keyframed plain element sometimes leaves the box 230-400px off (edit-accuracy seqplainkeys-none-*) #6989): not run

Unstable (2)

seqrotatenudge-none-pct-r0-root-z100: tracking 0.03, pressJump 0, drop 0, reload 3.03, render 0.04, renderKey -, undo false, teleport true / tracking 0.03, pressJump 0, drop 0, reload 0, render 0.08, renderKey -, undo true, teleport true / tracking 0.03, pressJump 0, drop 0, reload 0, render 0.08, renderKey -, undo true, teleport true
seqrepeat-none-center-r0-root-z100: tracking 0.05, pressJump 0, drop 0, reload 0, render 0.02, renderKey -, undo true, teleport true / tracking 0.05, pressJump 0, drop 0, reload 0, render 0.02, renderKey -, undo true, teleport true / tracking 0.05, pressJump 0, drop 0, reload 0, render 0.02, renderKey -, undo true, teleport true

heygengenesis

Verdict: APPROVE · 0 blocker · 1 important · 1 nit · head fadf861

No blockers. Required CI is green on this head. The Homebrew skills-tag issue below is worth fixing before merge, because it brings back the CLI/skills mismatch that #7013 closed. Details are inline.

Scope

Read end-to-end: update.ts, upgrade.ts (upgradePlan / upgradeRunningCli), installerDetection.ts, updateCheck.ts, skillsUpdateCheck.ts, skills.ts, doctor.ts, and the cli.ts exclusion list. Checked against backgroundChecks.ts (the 1h attempt backoff also caps the new always-due case for builds newer than npm latest) and prompts.confirmationRequired (it throws, so an unattended run without --yes cannot fall through to an install). Skimmed the tests and docs. There were no prior reviews.

— Genesis

…ills count Genesis review on #7094: - `brew upgrade hyperframes` installs the formula's version, which lags npm, and exits 0 on a no-op. `update --yes` now reads the linked binary's version afterwards and installs the skills at that tag; it reports "unchanged" (or "unverified") instead of claiming npm's latest. npm, pnpm and bun pin the exact version, so they keep using it. - `_meta.skillsOutdated` is dropped once the cached count is over 24 h old, so it cannot freeze when HYPERFRAMES_NO_UPDATE_CHECK (or CI/dev) stops the background checks. — wanbi Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

heygengenesis

Verdict: APPROVE · 2 resolved, 0 open, 0 new · fadf861 → 00c30fb

— Genesis

#7094 changes the same interval as part of updating the CLI and skills together, so this PR keeps out of it.

… update Single commit of #7094 on top of main (no merge commits through the signed GraphQL path). Includes: 2h update/skills check interval and stale-cache recheck; `_meta.checkedAt`, `_meta.skillsOutdated`, `_meta.skillsMissing`; `_meta.updateNotice`, one sentence for the agent to relay to the person, at most once a day per project (brew/npx-aware command, omitted under CI, the update-check opt-out and agent plugins); `hyperframes update [--check] [--yes] [--json]` (CLI then skills at the installed CLI's tag; brew version read back); doctor names the running binary and its channel; the hyperframes-cli skill gets one line to pass the notice on, naming no command. Keeps main's install-target skills check (#7120) in updateSkills. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

heygengenesis

Verdict: APPROVE · 0 open, 0 new · 00c30fb → 92d59ab (rebuilt on main)

Scope

Re-read the whole diff on the new base, including how update's skills check works alongside #7120's write-destination change. Wording check: _meta.updateNotice is addressed "For the user:", and the SKILL.md line leaves the decision to the person. If an agent runs the command anyway, update stops without --yes (exit 2) and says "Ask the person first", before it touches the network or installs anything. CI run 41770055641 is green at this head.

— Genesis

- `_meta.updateNotice` (and `update --check`'s skills command) now name a command that moves the running install: a global npm/pnpm/bun/brew CLI runs its own `hyperframes update` (or just its manager's command when only the CLI is behind), since `npx hyperframes` would run a project's copy or a fresh npx one; a project-local CLI moves with its project's manager by lockfile (`npm install`/`pnpm add`/`bun add`/`yarn add hyperframes@<v>`), which `update --yes` now names too instead of `npx hyperframes@latest`. - `update`'s confirmation hint states a fact and names no step for the agent: "Updating is the person's call; `update --check` only reports." - `upgrade --json`, `upgrade --project --json` and every `skills` JSON output leave out `_meta.updateNotice` (NO_UPDATE_NOTICE), like `update`. - dailyNotice: a null/non-object file reads as empty and is repaired; a future timestamp is stale; writes go through a 0600 tmp file + rename; withMeta never throws from the notice. - Docs: --json without --yes exits 2; plugin `update` exits 1 (plugin_managed); full `_meta` sample; per-install notice commands. `update --check` says "npm registry not reached" instead of "latest". Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

heygengenesis

Verdict: APPROVE · 0 open, 0 new · 92d59ab → 8120874

— Genesis

DeltaVerdict D5 fails any text an agent reads that tells the agent to install, update or remove skills, even when gated on the user. #7094 and #7102 fixed the update notice and skills/; the scaffolded CLAUDE.md and AGENTS.md, CLI output and the quickstart prompt still told the agent to run `skills update`. Reword them to state the fact and name the command the person runs ("For the user: ..."), matching the #7094 `_meta.updateNotice` style. The two scaffold templates stay byte-identical. No behavior changes. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

…en-com#7160) * fix(cli): address skills install and update hints to the person DeltaVerdict D5 fails any text an agent reads that tells the agent to install, update or remove skills, even when gated on the user. heygen-com#7094 and heygen-com#7102 fixed the update notice and skills/; the scaffolded CLAUDE.md and AGENTS.md, CLI output and the quickstart prompt still told the agent to run `skills update`. Reword them to state the fact and name the command the person runs ("For the user: ..."), matching the heygen-com#7094 `_meta.updateNotice` style. The two scaffold templates stay byte-identical. No behavior changes. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(cli): address media-use repair and update --check hints to the person Review follow-up on heygen-com#7160. The media-use SFX repair error and its `resolve --doctor` line still told the agent to run `npx hyperframes skills update media-use`; `update --check` printed a bare `Run: <cmd>`; and the README addressed agents directly. Reword them in the "For the user:" form. The JSON `fix` field keeps the bare command. Pin the wording in tests: both scaffold templates, the stderr nudge, the `init --skip-skills` hint, the media-use error and doctor line, and the `update --check` output. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

mintlify Bot deployed to staging - docs November 3, 2026 14:19

View deployment

heygengenesis Bot approved these changes Nov 3, 2026

View reviewed changes

Comment thread packages/cli/src/commands/update.ts Resolved

Comment thread packages/cli/src/utils/updateCheck.ts Resolved

mintlify Bot deployed to staging - docs November 3, 2026 15:04

View deployment

heygengenesis Bot approved these changes Nov 3, 2026

View reviewed changes

WaterrrForever added a commit that referenced this pull request Nov 3, 2026

revert(cli): leave the update-check interval to #7094

3ee1e9f

#7094 changes the same interval as part of updating the CLI and skills together, so this PR keeps out of it.

WaterrrForever mentioned this pull request Nov 3, 2026

fix(cli): two CLI fixes from Wenbo's reverse test (paywall link, plan label) #7099

Merged

mintlify Bot deployed to staging - docs November 3, 2026 18:12

View deployment

jrusso1020 mentioned this pull request Nov 4, 2026

fix(cli): check skill freshness at the install destination #7120

Merged

6 tasks done

Vitozhu04 force-pushed the wanbi/cli-update-check branch from 609b89e to 92d59ab Compare November 4, 2026 03:55

mintlify Bot deployed to staging - docs November 4, 2026 03:58

View deployment

heygengenesis Bot approved these changes Nov 4, 2026

View reviewed changes

mintlify Bot deployed to staging - docs November 4, 2026 08:36

View deployment

heygengenesis Bot approved these changes Nov 4, 2026

View reviewed changes

Vitozhu04 added this pull request to the merge queue Nov 4, 2026

Merged via the queue into main with commit 7cb6018 Nov 4, 2026
85 checks passed

Vitozhu04 deleted the wanbi/cli-update-check branch November 4, 2026 09:50

Vitozhu04 mentioned this pull request Nov 4, 2026

docs(skills): stop directing the agent to install, update or remove skills #7102

Merged

miguel-heygen mentioned this pull request Nov 4, 2026

chore: release v0.9.11 #7152

Merged

Vitozhu04 mentioned this pull request Nov 4, 2026

fix(cli): address skills install and update hints to the person #7160

Merged

heygengenesis Bot mentioned this pull request Nov 9, 2026

docs(changelog): weekly digest 2026-11-02-2026-11-09 #7453

Merged

Navigation Menu

Repository navigation

feat(cli): surface outdated CLI and skills to agents; add hyperframes update --check - #7094

feat(cli): surface outdated CLI and skills to agents; add hyperframes update --check#7094
Vitozhu04 merged 2 commits into
mainfrom
wanbi/cli-update-check

Vitozhu04 commented Nov 3, 2026 •

edited

Loading

Uh oh!

mintlify Bot commented Nov 3, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Nov 3, 2026 •

edited

Loading

Uh oh!

heygengenesis Bot left a comment

Uh oh!

Uh oh!

Uh oh!

heygengenesis Bot left a comment

Uh oh!

heygengenesis Bot left a comment

Uh oh!

heygengenesis Bot left a comment

Uh oh!

Uh oh!

This branch was successfully deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

Vitozhu04 commented Nov 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

How tested

Uh oh!

mintlify Bot commented Nov 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Nov 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Edit accuracy: accurate 267 (base branch 267), smooth 115 of those

Uh oh!

heygengenesis Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

heygengenesis Bot left a comment

Choose a reason for hiding this comment

Uh oh!

heygengenesis Bot left a comment

Choose a reason for hiding this comment

Uh oh!

heygengenesis Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

This branch was successfully deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Vitozhu04 commented Nov 3, 2026 •

edited

Loading

mintlify Bot commented Nov 3, 2026 •

edited

Loading

github-actions Bot commented Nov 3, 2026 •

edited

Loading